'\"macro stdmacro
.\"
.\" Copyright (c) 2022 Red Hat.  All Rights Reserved.
.\" Copyright (c) 2017 Ken McDonell.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMTIMEVALNOW 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmtimevalNow\f1,
\f3pmtimevalInc\f1,
\f3pmtimevalDec\f1,
\f3pmtimevalAdd\f1,
\f3pmtimevalSub\f1,
\f3pmtimevalToReal\f1,
\f3pmtimevalFromReal\f1,
\f3pmtimevalTotimespec\f1,
\f3pmtimevalPrint\f1 \- helper routines for time stored as a struct timeval
.SH "C SYNOPSIS"
.ft 3
.ad l
.hy 0
#include <pcp/pmapi.h>
.sp
void pmtimevalNow(struct timeval *\fItv\fP);
.br
void pmtimevalInc(struct timeval *\fIap\fP, const struct timeval *\fIbp\fP);
.br
void pmtimevalDec(struct timeval *\fIap\fP, const struct timeval *\fIbp\fP);
.br
double pmtimevalAdd(const struct timeval *\fIap\fP,
'in +\w'double pmtimevalAdd('u
const\ struct\ timeval\ *\fIbp\fP);
.in
.br
double pmtimevalSub(const struct timeval *\fIap\fP,
'in +\w'double pmtimevalSub('u
const\ struct\ timeval\ *\fIbp\fP);
.in
.br
double pmtimevalToReal(const struct timeval *\fIval\fP);
.br
void pmtimevalFromReal(double \fIsecs\fP, struct timeval *\fIval\fP);
.br
void pmtimevalTotimespec(struct timeval *\fItvp\fP, struct timespec *\fItsp\fP);
.br
void pmtimevalPrint(FILE *\fIf\fP, const struct timeval *\fItp\fP);
.sp
cc ... \-lpcp
.hy
.ad
.ft 1
.SH DESCRIPTION
.B pmtimevalNow
is a platform-independent method that returns the current system time
since the Epoch in
.IR tv .
.PP
.B pmtimevalInc
adds the time in
.I ap
to the time in
.I bp
and stores the result in
.IR ap .
Similarly
.B pmtimevalDec
subtracts the time in
.I bp
from the time in
.I ap
and stores the result in
.IR ap .
.PP
.B pmtimevalAdd
(and
.BR pmtimevalSub )
add (and subtract) times and return the result as a double value.
The time in the
.I ap
argument is not changed.
.PP
.B pmtimevalToReal
converts the time in
.I tp
to an equivalent double value.
.B pmtimevalFromReal
provides the reverse conversion, taking the time in
.I secs
and returning the equivalent time in
.IR val .
.PP
.B pmtimevalTotimespec
converts the struct timeval
.I tvp
into an equivalent struct timespec
.I tsp
(modulo rounding microseconds up to nanoseconds).
.PP
.B pmtimevalPrint
prints the timestamp from
.I tp
on the stream
.I f
in the local time (as returned by
.BR pmLocaltime (3))
in the format HH:MM:SS.XXX.
.SH NOTES
For variants of these interfaces using nanosecond precision
and the timespec structure, refer to
.BR pmtimespecNow (3).
.SH COMPATIBILITY
Prior to PCP 7.0 the routine
.B pmtimevalPrint
was called
.BR pmPrintStamp .
To support PMAPI transition, the old routine can still be used
if applications are recompiled with
.BR \-DPMAPI_VERSION=2 .
.PP
.B pmPrintStamp
is now deprecated and compile-time support for
this routine name will be removed in a future release.
.SH SEE ALSO
.BR gettimeofday (2),
.BR time (2),
.BR PMAPI (3),
.BR pmLocaltime (3)
and
.BR pmtimespecNow (3).

.\" control lines for scripts/man-spell
.\" +ok+ XXX HH SS {all rom HH:MM:SS.XXX}
